home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 726-750 / 743 / turbodex / dex.doc < prev    next >
Text File  |  1995-03-18  |  56KB  |  1,416 lines
  1.  
  2.                     TurboDEX Compiler v1.2 by $#%!
  3.  
  4.                              M A N U A L
  5.  
  6.  
  7.         Contents:
  8.  
  9.         1. Introduction, The Features
  10.         2. Installation And Running
  11.         3. The Language In General
  12.                 4. Step by step Tutorials
  13.         5. Alfabetical Overview Of Instructions
  14.                 6. Function() overview.
  15.                 7. Advanced Programming And Language Info's
  16.         8. Additional Info's
  17.  
  18.  
  19.  
  20. -------------------------------------------------------------------------
  21.                   CHAPTER 1, INTRODUCTION; THE FEATURES. 
  22. -------------------------------------------------------------------------
  23.  
  24. What is DEX ?
  25. DEX is a Compiler-Language, like C, Modula2, GfaBasic, Pascal etc. it
  26. features a similar programming structure and programming possibilities as
  27. above languages. Yet you'll have to consider that DEX as to offer a lot
  28. more, and, on the other hand, some aspects of the language are less
  29. flexible.
  30.  
  31. NEW FEATURES ADDED FROM v1.1 TO v1.2
  32. - DataType STRING, together with 14 functions to modify strings,
  33.   as StrAdd(), StrCmp(), Instr(), ReadStr(), Val(), StrCopy() etc.
  34. - 16 very handy miscelanious functions to make life easier: a.o.
  35.   OpenW(), OpenS(), Gadget(), FileLenght(), MouseX() etc.
  36. - Various small enhancements and bug fixes, like:
  37.   flexible comments /* */ and Constants TRUE, FALSE and NIL,
  38.   interrupting compilation by pressing both mousebuttons.
  39. - New example sources.
  40.  
  41. Dex Features:
  42. - Short Executables; small to medium size DEX-sources will compile nearly
  43.   always compile to less than 1K, where above languages will need nearly
  44.   always more than 5K. (examples: the program given as an example with
  45.   the WRITE statement in the reference section would compile into an
  46.   executable of ± 300 bytes, the code of a complete vectordemo was done in
  47.   ± 1300 bytes. All inclusive hunks, reloc-tables, opening of librarys etc.) 
  48. - Clear assembly source output: DEX generates fully commented assembly
  49.   source, in which you will be able to find all the variables you used,
  50.   and compare the code-generation directly to the DEX-source.
  51. - Direct access of all routines of EXEC, DOS, INTUITION, GRAPHICS and MATH,
  52.   without ANY includefiles and without opening ANY library. All 
  53.   customchip registers can adressed by their name, without ANY include.
  54. - Handy features like Global/Local variables, easy calling of 
  55.   procedures and libraryroutines with return values, inline assembly
  56.   code, use of registervariables.
  57. - Faaast executables, extensive use of registers, fast parameter passing,
  58.   smart solutions for local variables and structs, quick optimization,
  59.   pc relative branching and adressing, special HYPER optimize mode for loops.
  60. - Easy to manage development system: just one compiler will do the job,
  61.   no 5 meg of includes, linkfiles, objects, optimizers, profilers etc.
  62.   All instructions needed for writing a substancial program integrated
  63.   in the compiler.
  64.  
  65.  
  66. What is shit about TurboDEX?
  67. - some things haven't been implemented.
  68. - some errors which you might make while programming are not recognised,
  69.   and will be compiled, since no things like stack-overflow checking
  70.   are implemented.
  71. - Its mosly faster than above languages, but still not optimized enough.
  72. - it doesn't do any type-checking, so things like dividing a CHAR
  73.   variable by a LONG, or messing up pointers to wrong memory-area's
  74.   are not flagged by the compiler.
  75. - The compiler can be *very* slow sometimes
  76. - The development system is not adequate for big app's.
  77. - kick 2.0 compatible but not 2.0 specific (generates 1.2-and-up code).
  78. - It's not idiot-proof.
  79.   
  80. Generally, DEX gets you ASSEMBLY quality performance an size executables,
  81. with BASIC effort. But the prize to pay for this that the programmer
  82. needs to know what he's doing.
  83.  
  84. If you're eager to see what a DEX-source looks like, browse through
  85. the drawer with examples, kick-ass with 'HelloWorld.dex', then check
  86. out the other small sources. For your convenience here's some example:
  87.  
  88. /* Nominated for most boring example */
  89.  
  90. PROC main()
  91.   WRITE 'Hello, World!\n'
  92. ENDPROC
  93.  
  94.  
  95.  
  96. -------------------------------------------------------------------------
  97.                        2. INSTALLATION AND RUNNING
  98. -------------------------------------------------------------------------
  99.  
  100. How to work with TurboDEX.
  101. First of all: all you really need is the compiler 'DEX'. just type
  102. something like:
  103.  
  104. DEX [-opts] <sourcefile>
  105.  
  106. example:
  107.  
  108. DEX:> dex -a helloworld
  109.  
  110. the compiler will take a pure ascii file with the name 'HELLOWORLD.DEX'
  111. as input in the current directory (this file contains some dex program
  112. you wrote), and will produce a file 'HELLOWORLD.S' as output (this file
  113. contains the assembly language translation from your DEX-source).
  114. The -a flag will cause DEX to invoke A68k and Blink straight away, to
  115. assemble and link the .S file..
  116. Now type:
  117.  
  118. DEX:> HELLOWORLD
  119.  
  120. Hello, World!
  121.  
  122. DEX:>
  123.  
  124. If you don't use the -a flag, you'll have to assemble by hand. Almost
  125. any assembler will do, supported are A68k and DEVPAC (tm).
  126. Compile with an assembler like A68K and link it with for example Blink:
  127.  
  128. Dh0:> A68K HELLOWORLD.S
  129. Dh0:> BLINK HELLOWORLD.O
  130.  
  131. Another example:
  132.  
  133. Dh0:> dex -flgr
  134.  
  135. This will enable you to pick your source by means of a file-requester,
  136. dex will generate a list-file, invoke Devpac's GENAM instead of the
  137. A68k/Blink duo, and execute your program afterwards.
  138.  
  139. Above is all you need.
  140.  
  141. Additional suggestions:
  142. Best you shove DEX into your C: dir next to A68K and BLINK.
  143. You may want to make Genam or Blink resident to speed up the process,
  144. and if don't own a HD, copy DEX to ram: so you can 
  145. Compile-Assemble-Link-Run without disk Access.
  146. NOTE: DEX outputs code suitable for A68K, so if you'd like to use
  147. some other Assembler, you could be forced to make some minor changes.
  148. (see -o option).
  149.  
  150. CommandLine Options:
  151. Executing DEX with nothing following it will result in DEX opening
  152. a window, where you can enter the commandline at the 'IN>' prompt.
  153.  
  154. options:
  155. ?   Display a 'usage:' and some info
  156. -a  If compiling succeeded, invoke A68K and BLINK from the compiler.
  157.     NOTES: both need to be in the search-path (i.e: mostly C: or the
  158.     active directory). this will need c:run (<2.0) and some free-memory.
  159. -c  Don't add comments to assembly source (because you're not interested
  160.     in the generated code anyway), makes file smaller.
  161. -f  Pops up a filerequester to let you choose a source to compile
  162.     instead of having to enter it at the commandline.
  163. -g  Have GENAM (part of the Devpac (tm) assembler) assemble and
  164.     link your program. Includes -o, excludes -a.
  165. -l  Produce a list file named <source>.LIST, containing statistical
  166.     info's about the program, the compiler-status, and lists of
  167.     identifiers, procedures etc.
  168. -o  Generate assembly source for any other assembler than A68k.
  169. -r  Run the executable after being generated. needs -a or -g
  170. -s  Try to generate code that is more reliable, but slower. The compiler
  171.     will insert extra intructions to do extending of wrong-size variables,
  172.     and make some extra checks. This option must only be used for
  173.     test-purposes. Not guaranteed to help.
  174. -t  Don't compile file at the command line, but internal test-source
  175.     instead (for test-purposes only).
  176.     
  177. NOTE: options are case-INsensitive, may be put anywhere on the commandline,
  178. and can be but together. so 'DEX -c test -A' has the same effect as
  179. 'DEX -ac test'.
  180.  
  181. NOTE2: Genam may act weird sometimes due to the fact that it probably
  182. expects being run from devpac when it isn't run run from a shell. if
  183. this bothers you, write a small script to run dex and genam, and leave -g.
  184.  
  185. Ok. Now over to the real stuff:
  186.  
  187. -------------------------------------------------------------------------
  188.                          3. THE LANUAGE IN GENERAL
  189. -------------------------------------------------------------------------
  190.  
  191. Procedures.
  192. All programming instructions are gathered in modules, called PROCs.
  193. The most important of these is the procedure PROC main() which always
  194. has to be part of a program (it doen't have to be the first procedure).
  195. this is the actuall program, where all variables are global. Other
  196. procedures can be added, that can have own (local) variables. These
  197. procedures can be called with or without parameters, like: 
  198. 'VOID getpicture(rastport,x+4,y/8)' 
  199. Procedures cannot be called recursively.
  200.  
  201. Loops.
  202. Lots of loops are supported, like FOR ... ENDFOR, WHILE ... ENDWHILE and
  203. some others. These can be nested infinetely (well, nearly).
  204.  
  205. Variables.
  206. At the moment 11 types of variables are supported:
  207. - LONG, a 32 bit wide integer variable, can hold any value from 
  208.   somewhat less than -2.14 to a little more than 2.14 milliard. this
  209.   is the most used variable since all addresses are kept in these,
  210.   most system routines expect longints, and nearly all calculations
  211.   are done in 32 bit.
  212. - INT, a 16 bit variable, keeps values from -32k to +32k. Used with
  213.   multiplies/divides.
  214. - CHAR, an 8 bit variable, most used with texts, and other small data.
  215.   range 0 to 255.
  216. - STRING, defines a string that may be modified, and used especially
  217.   for complex string manipulations. example:
  218.   DEF s=100:STRING
  219.   s may now be modified by special string functions. see chapter
  220.   on (string-)functions for more info.
  221. - REGLONG, REGINT and REGCHAR. These are the same ase those three described
  222.   above, with some small differences: - max. 6 of them can be used per
  223.   module, - 680x0 registers are used for their storage. 
  224.   The advantage of these is mainly their speed, as wel as the smaller and
  225.   better code they produce. They are best used with DOWN loops, and 
  226.   everywhere you need to have a certain part of your program to be as
  227.   faaast as possible.
  228.   NOTE WELL: these may only be declared with LOCAL
  229. - ARRAY and ARRAYCHIP. These are simple implementations of arrays, and 
  230.   function as CharArray only. They are defined as variable, and the
  231.   variable (compatible with LONG) contains a pointer to the array.
  232.   ARRAYCHIP is the version of ARRAY where the array is forced to 
  233.   chipmem. (for the 'insiders': BSS_c ).
  234. - CUSTOMREGS. all customregs can be used as variable. Just type the 
  235.   official name in capitals, like DMACON. this enables lines like:
  236.   AUD0LEN := samplelen/2   or even   COLOR00 := VPOSR*VHPOSR
  237.   its up to you to see which registers you can read or write.
  238. - ABSOLUTE, if you would write or read absolute addresses, you can
  239.   use a value (specifying the adress) between [], following the variable-
  240.   name in the definition, like: sysbase[4]:LONG, would enable you to
  241.   use sysbase as an absolute variable. Like this you can specify a
  242.   variable as part of a STRUCT, which provides extremely flexibel
  243.   programming, like: depth[newscreen.8]:INT
  244.  
  245. all these variables (except for the CustomRegs) have to be defined before
  246. use. See DEF in the reference section for more info's.
  247.  
  248. Other parameters.
  249. these can be used as value only.
  250. supported in this version are:
  251. - Values: dependent on the instruction you use, values like 4, 100,
  252.   4543836, $ff, $c00000, %101110 etc. can be used.
  253. - Adresses of labels and STRUCTS. you may need to now the address of a
  254.   label or stuct in your program. e.g. if somewhere in your program is
  255.   something like 'PROC text()', 'STRUCT text' or 'text:' the address could
  256.   be obtained with  adr := {text}  (use {} with the labelname).
  257. - a constant. currently, you can't define them yourself. only these are
  258.   available: TRUE (=-1), FALSE (=0), NIL (=0)
  259. - A text string. in the current version, strings that can be altered
  260.   are not supported. Though, you may give a string between '' as a
  261.   parameter. if the string is one character long, the ascii code will
  262.   be passed: c := 'A' equals c := 65 . If the string is longer, however,
  263.   the address of the string is passed, thus enabling flexible programming
  264.   were routines need the address of a textstring, for example:
  265.   VOID Text(rast,'Hello There !',LEN). LEN is a systemvariable, always
  266.   containing the lenght of the last string used. In the string you
  267.   may use the following codes:
  268.   \n    a return + linefeed (ascii 10 and 13)
  269.   \a    an apostophe, the one you need for enclosing the string
  270.   \t    insert a TAB (9)
  271.   \f    a linefeed (ascii 10)
  272.   \e    insert an escape-code (27), '\e[' will work as CSI.
  273.   \0    a null byte (not often needed, as all strings in DEX
  274.         are terminated with a '0').
  275.   \\    a backslash.
  276.         example: 'this: \a\\\a is a backslash \n\0'
  277.         Additionally, following codes may be used only when using a
  278.         string as part of a WRITE-statement:
  279.   \d    print out a LONG as decimal.
  280.   \h    print out a LONG as hexadecimal
  281.   \c    print out a LONG as character
  282.   \s    print out a 0-terminated string at address.
  283.   \w<x> sets minimum width for print, rest will be padded with spaces.
  284.   \z    pad with zeroes instead of spaces.
  285.   \m<x> sets maximum width for strings.
  286.   \l    put data to the right of the field (default).
  287.   \r    put data to the left in the field instead of to the right.
  288.         example:
  289.         WRITE 'some results: \z\w8 $\h \c.',65535,65
  290.         will print:
  291.         some results:  $0000FFFF A.
  292.   note: changes to print-formatting made with \w\z\m\l\r are only
  293.         valid within one WRITE-statement, they are reset to default
  294.         values at the start of the next statement.
  295. - A string as integer value. you may use strings of lenght 1-4 between
  296.   double quotes ("") to, for example, quickly compare short strings:
  297.   
  298.     IF {buffer}="FORM"               and          a := "A"
  299.  
  300.   are equal to
  301.  
  302.     IF {buffer}=$464F524D            and          a := 65
  303.  
  304.   The first character is stored in the MSB of the LONG. If only
  305.   one character is supplied, it is stored in the LSB.
  306.       
  307.  
  308. Parameters needed;
  309. mostly a parameter could be one of 2 different types, in the description
  310. of the commands that follows specified as var or exp.
  311. var = parameter that must be a variable. examples;
  312.       a, count, COLOR01, etc.
  313. exp = parameter that can be a variable, a value, or an expression (a
  314.       combination of more aspects). examples;
  315.       1, 200, $ff, a, DMACON, count+3/a-2000
  316.       these can be all mentioned above, including combinations.
  317. For example, the parameter of FOR that is the counter would be a var,
  318. and the two parameters specifying the range could be any exp(ression).
  319.  
  320. Expressions.
  321. as stated above, everywhere an instructions needs a parameter that is
  322. is an exp, you can use any of these operators with variables/values mentioned:
  323. -,+      minus and plus, no restrictions.
  324.          examples: 3+a, 60-{text}+$ff
  325. /,*      divide and product, these are always done 16bit wide, watch
  326.          carefully when using them. examples: a/20, counter*256.
  327.          for 32bit operations, see MUL() and DIV().
  328. &,^      AND and OR, used only as mathematical, not logical operators.
  329. =,<,>,?  comparisons. in the current version they are only usefull with
  330.          IF and WHILE. They need to be the last operator used.
  331.          In order: equal, smaller than, bigger than or equal, unequal.
  332.          examples: a=3, {data}-1024>$c00000, flag?0, 3*b>a
  333. IMPORTANT: in the current version of the compiler, expressions are compiled
  334. in the same order as written in the sourcecode, and () are not supported.
  335. thus, a+(3*b) shouldn't be written as a+3*b, but 3*b+a, otherwise a+3 would
  336. be calculated first, instead of 3*b. same goes for comparison (!) operators.
  337.  
  338. Labels and remarks.
  339. labels stand on their own line.
  340. a label is any string followed by a ':' and can be used only to point at
  341. instructions, not structs etc. (see above) example:
  342. startofprogram:
  343. when you program very structured, you won't need labels.
  344. two types of remarks are supported: remarks that start with a ' and
  345. stand on their own line. f.e.:
  346. ' Here the screen is setup
  347. /* or remarks that may be anywhere within the source, also on multiple
  348.    lines (not nested), as around this sentence  */
  349.  
  350.  
  351. Syntax.
  352. first of all, the only place where spaces are obigatory, is after an
  353. instruction keyword: WHILE<space>a=3
  354. furthermore, the whole language is case sensitive.
  355. uppercase: keywords, customregisternames
  356. lowercase: variablenames, labelnames, procnames, structnames
  357. both     : systemcallnames, Dex additional functions.
  358.            every part of the name starts of with an uppercaseletter,
  359.            like: VOID WindowToFront(), VOID OpenW()
  360.  
  361. Startup options.
  362. optional keywords about what sort of startup-code TurboDEX should
  363. generate, may be given between the brackets of PROC main() :
  364. ARG     The variables 'argadr' and 'argl' contain the command-line
  365.         passed to your program (both LONG).
  366. WB      Code will be added to start your program from workbench too.
  367.         NOTEZ BIEN: you need to supply a value for stdout
  368.         if you write a WB program that uses WRITE.
  369.         best is to open a CON:
  370. DETACH  makes a program auto-detaching, can be started from shell
  371.         without 'C:RUN'
  372. INIT    compiles no initcode at all, no opening of librarys etc,
  373.         for programs that need to be _VERY_ small (<200 bytes),
  374.         rarely usefull.
  375. example: PROC main(ARG)
  376. NOTE: it is not advisable to use more than one option at a time.
  377.  
  378. Build-In Variables:
  379. Presently, seven of them may be used: stdout, dosbase, graphicsbase,
  380. intuitionbase and mathffpbase (execbase is DEF sysbase[4]:LONG).
  381. When using these variables, code is genereated to provide a correct
  382. contents, and, when using a function from a library, the base is also
  383. defined. stdout contains the output filehandle (mostly the shell window),
  384. when using the WRITE statement: when it's 0, you can open a CON:, and
  385. put it's filehandle into the variable stdout. Furthermore, the variables
  386. argadr and argl (both LONG) may be used if the flag ARG is used
  387. in the header of main().
  388.  
  389.  
  390.  
  391. ------------------------------------------------------------------------
  392.                        4. STEP BY STEP TUTORIALS
  393. ------------------------------------------------------------------------
  394.  
  395. Assuming you copied DEX, A68K and BLINK to your C: directory, made
  396. a directory for storing your sources and the examplesources, and
  397. started up some editor to get things going, i will now give some small
  398. tutorials on DEX-programming.
  399.  
  400. Best you try to get the HelloWorld.dex program running first. This
  401. will give you a good impression on how the system works. load it in your
  402. editor to see what it looks like:
  403.  
  404. ' The HelloWorld program in DEX !
  405.  
  406. PROC main()
  407.   WRITE 'Hello, World!\n'
  408. ENDPROC
  409.  
  410. Now, change it to your needs, save it, and compile it with:
  411.  
  412. DEX HelloWorld -a
  413.  
  414. After all compiling has been done, check the directory the source is
  415. in. It should now contain two new files: HelloWorld.s and HelloWorld.
  416. I'll get back later on the contents of the .s file, now just execute
  417. the program by typing it's name. Please take note of the small size
  418. of the executable (i guess about 300 bytes).
  419.  
  420. You now used the basis of any dex program: the PROC main().
  421. this is the minimum of any program: you may add other procedures,
  422. which may have arguments and local variables. The WRITE instruction
  423. can be used for many more purposes than just writing string-contants:
  424. it can print variables in decimal, hexadecimal and ascii format,
  425. and nil-terminated strings. as an example we will now make a program
  426. that prints the starting address of the exec.library to the screen:
  427.  
  428. PROC main()
  429.   DEF sysbase[4]:LONG
  430.   WRITE 'execbase = $\h',sysbase
  431. ENDPROC
  432.  
  433. Here we do something new, we declare a global variable, like 'a'
  434.  
  435. DEF a:LONG
  436.  
  437. but now we state we would like to have it at a fixed address, $00000004.
  438. We can print out the contents of the variable sysbase by putting
  439. the formatcode '\h' (hexadecimal) in the outputstring, and the value
  440. following it.
  441.  
  442. I will now discuss some of the programs to be found in the directory
  443. with example sources to show how small programs could be developped.
  444. First here's the SHELL.DEX program:
  445.  
  446. /* TurboShell in TurboDEX */
  447.  
  448. PROC main(DETACH)
  449.   DEF window:LONG, buffer=60:ARRAY, a:REGLONG, text:REGLONG
  450.   window := Open('con:10/10/400/100/TurboShell v0.0\0',1006)
  451.   VOID Write(window,'Shell by $#%! in 1991. \aquit\a to stop.\n',LEN)
  452.   WHILE text?"quit"
  453.     VOID Execute(buffer,0,window)
  454.     VOID Write(window,'Turbo> ',LEN)
  455.     a := Read(window,buffer,59)
  456.     MCHAR buffer+a,0
  457.     text := MLONG(buffer)
  458.   ENDWHILE
  459.   VOID Close(window)
  460. ENDPROC
  461.  
  462. It's a very small program that show's clearly enough how to use some of
  463. the language's features. Here's a step-by-step explanation of how
  464. it works:
  465.  
  466. Because it's a small program, all code is gathered in one procedure,
  467. and we tell the compiler that we want to give the Shell-prompt back
  468. after our program is loaded with the DETACH option. Now we define
  469. a couple of variables for use in the program: in 'window' we will
  470. store the filehandle to our CON:-window, 'a' and 'text' are for use
  471. lateron and buffer is an array of 60 bytes, which we will use to store
  472. the commandline Note that 'buffer' is actually a variabele of the type
  473. LONG which contains a pointer to that array. Now we use Open() from
  474. the dos.library to open our console window, and we do not check if
  475. an error occurred, for the simplicity of the example. Note that you
  476. do not need include-files modules to be linked or whatever to be 
  477. able to use functions like Open, they're build in to the language.
  478. Now we use the dos.library Write() (not the DEX WRITE!) to output
  479. a message to it: We could have done this using WRITE, but the example
  480. is about system-functions. Now we come in a loop which we will only
  481. exit if 'text' is unequal to the (LONG-encoded) string "quit".
  482. In this loop, we will Read() something from the console, and then
  483. Exexute() it as a cli-command. Note that we use MCHAR (put a CHAR-sized
  484. value into memory) to terminate the string.
  485.  
  486. Here's a somewhat longer example to get the feeling of how things
  487. are done in DEX, COLORSCREEN.DEX
  488.  
  489. /* Open a screen and do something */
  490.  
  491. PROC main()
  492.   DEF rast:LONG,screen:LONG
  493.   DEF sx:REGINT, sy:REGINT
  494.   screen := OpenS(320,256,5,0,' TurboDEX Screen ')
  495.   rast := screen+84
  496.   IF screen?FALSE
  497.     MOUSE
  498.       DOWN sx,320
  499.         DOWN sy,256
  500.           VOID SetAPen(rast,sx*sy)
  501.           VOID WritePixel(rast,sx,sy)
  502.           JUMPMOUSE leave
  503.         ENDDOWN
  504.       ENDDOWN
  505.     ENDMOUSE
  506.     leave:
  507.     VOID CloseS(screen)
  508.   ENDIF
  509. ENDPROC
  510.  
  511.  
  512. We use the DEX functions new in v1.2 to open and close our screen:
  513. OpenW(), CloseS(). before we start plotting we have to be sure
  514. the screen was actually opened.
  515.  
  516. In the main program we enter the big MOUSE - ENDMOUSE loop which
  517. is very handy for demo-like programs like this one. it is accompanied
  518. by an extra JUMPMOUSE for faster exit. The inner loop draws the screen
  519. full of colourfull pixels. Note the VOID intruction: we're not interested
  520. in the returnvalues ( 'VOID' is like 'dummy:=' ), when calling the
  521. procedure screen(), we are: ENDPROC gives us the screenptr.
  522.  
  523. Now we will look at a complete utility in DEX, with errorchecks
  524. To make it usefull for everyday use: a three-column dir-command!
  525. DIRQUICK.DEX displays filelenght too and makes use of extended WRITE
  526. string-formatting.
  527.  
  528. /* nice directory command in dex ! */
  529.  
  530. PROC main(ARG)
  531.   DEF lock:LONG, info=260:ARRAY, ok:REGLONG, d:REGLONG, c:REGLONG
  532.   DEF dir:LONG
  533.   MCHAR argadr+argl-1,0
  534.   lock := Lock(argadr,-2)
  535.   IF lock?FALSE
  536.     ok := Examine(lock,info)
  537.     IF ok?FALSE
  538.       dir := MLONG(info+4)
  539.       IF dir>0
  540.         WRITE 'Directory of: \s\n',info+8
  541.         c := 0
  542.         WHILE ok?FALSE
  543.           ok := ExNext(lock,info)
  544.           INC 1,c
  545.           IF ok?FALSE
  546.             d := MLONG(info+124)
  547.             dir := MLONG(info+4)
  548.             IF dir>0
  549.               WRITE '\e[1;32m\w25\m25\l\s\e[0;31m',info+8
  550.             ELSE
  551.               WRITE '\w17\m17\l\s \r\w7\d',info+8,d
  552.             ENDIF
  553.             IF c=3
  554.               WRITE '\n'
  555.               c := 0
  556.             ELSE
  557.               WRITE ' '  
  558.             ENDIF
  559.           ENDIF
  560.         ENDWHILE
  561.         IF c?1
  562.           WRITE '\n'
  563.         ENDIF
  564.       ELSE
  565.         WRITE 'No Dir!\n'
  566.       ENDIF
  567.     ENDIF
  568.     VOID UnLock(lock)
  569.   ELSE
  570.     WRITE 'What ?!?\n'
  571.   ENDIF
  572. ENDPROC
  573.  
  574.  
  575. At every step in the program we check if an error may have occurred,
  576. and we put all the nested IF's into one procedure: after making the
  577. neccesary locks and examines, we read each entry, and put it directly
  578. on the screen, directory's and files each their own color for distinction.
  579. Those WRITE statements are good examples of somewhat more complex
  580. string/integer formatting. Note we keep track of the column we're in 
  581. with variable 'c'.
  582.  
  583. Here's short description of all other examples:
  584.  
  585. DIRSORT.DEX     An extented version of DIRQUICK.DEX, does a very
  586.                 slow bubble sort on the entries before displaying, and
  587.                 separates the directories from the files. can only read
  588.                 dir's with less than 400 entries (changeable).
  589. ASLREQ.DEX      a demo of how non-DEX-standard-kick-2-libraries may be 
  590.                 used: it puts up the ASL-filerequester, and checks
  591.                 nicely if you have KICK2, if it could open the library etc.
  592. PLAYSAMPLE.DEX  Show's how the buil-in hardware-register variables
  593.                 can be used to play a beep.
  594. COPPER.DEX      Show's the ease of copper-programming from DEX
  595. NEWWINDOW.DEX   Opens a intuition-window and output's a text it.
  596. GETARG.DEX      Show's how to handle commandline arguments from DEX.
  597. SPEED.DEX       Proggie to show off DEX's optimed loops.
  598. RESIDENT.DEX    Display's all exec resident modules. Shows how for example
  599.                 system lists can be dumped.
  600. VECTOR.DEX      A vectorDemo in DEX that rotates the word 'TurboDEX' on
  601.                 the screen in three colours, using the graphics.library,
  602.                 double-buffering and a precalculated-coordinate list
  603.                 in the file TDEX.BIN. If you want to compile
  604.                 this program, make sure the INCLUDE statement in the
  605.                 source points to where you have the .BIN file.
  606.  
  607. What's new in v1.2: (except the update of above examples)
  608.  
  609. MEM.DEX         a small utility to let you view any memory area
  610.                 with hex and asciidump as in a monitor, but now from
  611.                 a shell. very handy for debugging.
  612. QUICKLAUNCH.DEX a complete application launching utility in DEX.
  613.                 reads names of app's from a configfile in S:, then
  614.                 put's them in a window with DEX powerfull new
  615.                 GadGet() function. nice utility.
  616.  
  617. Furtermore in the directory PDexamples, you will find sources written
  618. by authors other than me, distributed as PD. currently this is only one.
  619.  
  620.  
  621.  
  622. -------------------------------------------------------------------------
  623.                5. ALPHABETICAL DESCRIPTION OF INSTRUCTIONS
  624. -------------------------------------------------------------------------
  625.  
  626. -----------
  627. AND, OR, NOT
  628. -----------
  629. syntax:      AND value,variable
  630.              OR value,variable
  631.              NOT variable
  632. description: Performs logical and, or and not on a variable.
  633.              NOTE: AND and OR  are also available as operators in an
  634.              expression (&,^).
  635. example:     AND $ff,c
  636.              NOT x
  637.  
  638. -----------
  639. ASM, ENDASM
  640. -----------
  641. syntax:      ASM
  642.              ENDASM
  643. description: all following this statement until ENDASM will not be compiled
  644.              by the compiler, and is put unchanged into the output file,
  645.              thus enabling inline assembly. if registers D2-D7 are used,
  646.              these should be put on the stack first. Make sure you use
  647.              distinct labels: best way is to prefix them.
  648. example      ASM
  649.                moveq #0,d0
  650.              ENDASM
  651.  
  652. -----------
  653. CALL
  654. -----------
  655. syntax:      CALL address, paraddress, returnvar
  656.              CALL base[offset], paraddress, returnvar
  657. par:         address = any memory location that is the start of a routine
  658.              base = base address of a library
  659.              offset = offset from a librarybase, like -552
  660.              paraddress = pointer to memory chunk of 14 longwords,
  661.              containing the parameters to a routine, in d0-d7/a0-a5 order.
  662.              returnvar = variable to put the returnvalue in
  663.              NOTE: both paraddress and returnvar are optional.
  664. description: this instruction enables you to call any assembly language
  665.              subroutine, and in particular librarycalls that are not
  666.              part of the DEX set.
  667.              see the ASLREQ.DEX source for a good example.
  668. example:     ' assuming you have an initialized variable called 'aslbase':
  669.  
  670.              CALL aslbase[-30],,reqadr
  671.  
  672.              ' this will call AllocFileRequest() from the asl.library 
  673.              ' reqadr may contain 0
  674.  
  675.  
  676. -----------
  677. CMOVE, CWAIT, CSKIP, CPART, CSTOP
  678. -----------
  679. syntax:      CMOVE value,customreg
  680.              CWAIT rastline,rastpos
  681.              CSKIP rastline,rastpos
  682.              CPART
  683.              CSTOP
  684. par:         customreg = valid name for a customchip register, like: BLTSIZE
  685.              rastline = beam y position (0-255)
  686.              rastpos = beam x position (0-$E0)
  687. description: Instructionset to code the copper coprocessor. these
  688.              instructions need to be gathered in a CHIPSTRUCT
  689.              See your Hardware Reference Manual for more information on
  690.              functioning of these instructions. CSTOP designates the 
  691.              end of a copper-list, CPART needs to precede any intructions
  692.              that are to be executed after rasterline 255.
  693. example:     ' Split screen in two colors and be very rude to multitasking;
  694.  
  695.              PROC main()
  696.                COP2LCH := {coplist}
  697.                INTENA := $4000
  698.                MOUSE
  699.                ENDMOUSE
  700.              ENDPROC
  701.  
  702.              CHIPSTRUCT coplist
  703.                CMOVE $fff,COLOR00
  704.                CWAIT 80,$01
  705.                CMOVE $f00,COLOR00
  706.                CSTOP
  707.              ENDCHIPSTRUCT
  708.  
  709. -----------
  710. DEC, INC
  711. -----------
  712. syntax:      DEC value,variable
  713.              INC value,variable
  714. description: Substracts or adds the value (-8 to 8 excluding 0)
  715.              to the indicated variable.
  716. example:     INC 2,count
  717.  
  718. -----------
  719. DEF, LOCAL
  720. -----------
  721. syntax:      DEF varname:TYPE [, ... ]
  722.              LOCAL varname:TYPE [, ... ]
  723. par:         type = any of the types of variables discussed in the above 
  724.              section of variabletypes (like LONG, ARRAY etc.)
  725.              varname = any string, signifying the name of the variable. may
  726.              be followed by = with a value (LONG, INT, CHAR only) to 
  727.              initialize it before use (default = 0). Using = with ARRAY
  728.              signifies the size of the array (like string=100:ARRAY).
  729. description: declares a variable before use, where DEF defines the
  730.              variables that can be used in any module (global), and LOCAL those
  731.              which can only be used in one module (local).
  732. example:     DEF adr:LONG, sign=25:CHAR, count:REGINT, string=256:ARRAY
  733.              LOCAL item[data.6]:INT, picture=10240:ARRAYCHIP
  734.  
  735. -----------
  736. DIV, MUL
  737. -----------
  738. syntax:      var := MUL(exp,exp)
  739.              var := DIV(exp,exp)
  740. description: MUL and DIV are 32 bit substitutes for the * and / operators.
  741.              The 68000 processor doesn't support 32 bit multiplication and
  742.              division, only 16 bit. dex compiles * and / using 16 bit,
  743.              for speed reasons, and tries to use 32 bit shifts when
  744.              possible. Mostly this isn't a problem, but when it is,
  745.              the slower DIV and MUL routines can be called to use
  746.              the full 32 bit.
  747.  
  748. -----------
  749. DOWN, ENDDOWN
  750. -----------
  751. syntax:      DOWN counter,loops
  752.              ENDDOWN
  753. par:         counter = (var) variable decreased by the loop
  754.              loops = (exp) number of times loops should be executed
  755. description: this is a simple FOR loop. the counter will be decreased
  756.              to zero, f.e. if you specify 100 for loops, the counter will
  757.              go from 99 to 0. the must end with an ENDDOWN.
  758.              NOTE: Because the only reason to use DOWN over FOR is
  759.              speed, it can only be used with REG variables (i.e. REGLONG).
  760. note:        do not use DOWN for loops that need to be done only once
  761.              or less.
  762. example:     DOWN count,1000000
  763.                ' fast loop here
  764.              ENDDOWN
  765.  
  766. -----------
  767. ENDPROC
  768. -----------
  769. syntax:      ENDPROC returnvalue
  770. par:         returnvalue = (exp) result of the PROC
  771. description: marks the end of a procedure and returnes a value to the
  772.              whatever called it. Default is zero
  773. example      see PROC example 2
  774.  
  775. -----------
  776. EXIT
  777. -----------
  778. syntax:      EXIT returnvalue
  779. par:         returnvalue (exp) = returncode for dos
  780. description: exits program at any point in the program.
  781. example:     EXIT 5
  782.  
  783. -----------
  784. FOR, ENDFOR
  785. -----------
  786. syntax:      FOR counter,start,end [,step]
  787.              ENDFOR
  788. par:         counter = (var) the variable that counts the loops
  789.              start = (exp) begin value of counter
  790.              end = (var or value) value for the loop to end with.
  791.              step = a value between 8 and -8 (excluding 0), default 1
  792. description: The loop will be executed as many times as specified by 
  793.              start and end. meanwhile, the counter is being increased
  794.              with every loop. as standard, the counter will be increased
  795.              by 1, specifying a step changes this.
  796. example:     FOR counter,0,319,2
  797.                VOID Move(rast,counter,0)
  798.                VOID Draw(rast,counter,255)
  799.              ENDFOR
  800.  
  801. -----------
  802. GOTO
  803. -----------
  804. syntax:      GOTO labelname
  805. description: continues the execution of the program within one module
  806.              at the place of the label.
  807. example:     IF a/20=3
  808.                GOTO someplace
  809.              ENDIF
  810.              ' rest of the program
  811.              someplace:
  812.  
  813. -----------
  814. IF, ELSEIF ELSE, ENDIF
  815. -----------
  816. syntax:      IF equation
  817.              ...
  818.              [ ELSEIF equation ]
  819.              ...
  820.              [ ELSEIF equation ]
  821.              ...
  822.              [ ELSE ]
  823.              ...
  824.              ENDIF
  825. par:         equation (exp) = expression to be equated.
  826. description: the programblock between IF and ENDIF will only be executed
  827.              if the expression is TRUE. if it is FALSE, however, it will
  828.              be skipped, and an ELSEIF block may be executed if that
  829.              equation is TRUE. If an ELSE block is present, it will only be
  830.              executed if all the other IF's were FALSE.
  831. example:     IF a>1000
  832.                WRITE 'hey dude, \d is a little too much!!!\n',a
  833.              ELSEIF a<0
  834.                WRITE 'what about that?\n'
  835.              ELSE
  836.                WRITE 'that's more like it!\n'
  837.              ENDIF
  838.  
  839. -----------
  840. INCLUDE
  841. -----------
  842. syntax:      INCLUDE filename
  843. description: Includes any binary file into the program. Statement
  844.              needs to be part of a STRUCT to be accessed properly.
  845.              filename doesn't need quotes.
  846.  
  847. -----------
  848. JUMPMOUSE
  849. -----------
  850. syntax:      JUMPMOUSE label
  851. description: If the leftmousebutton is pressed at the moment this
  852.              instruction is executed, execution of the program will be
  853.              continued at <label> (only within one module).
  854.  
  855. -----------
  856. LONG, INT, CHAR
  857. -----------
  858. syntax:      LONG value1, value2, ...
  859.              INT value1, value1, ...
  860.              CHAR value1, value2, ...
  861. par:         value = any number like 4, 100, $c00000 etc. additionally,
  862.              with CHAR you may use strings, like: CHAR 'hello\0', and with
  863.              LONG you may use the adresses of programlabels, like:
  864.              LONG vectordata .
  865. description: with these statements you can put data of the appropriate
  866.              format into your program. they are only usefull within a
  867.              struct.
  868. example:     anylabel:
  869.              structadr := {anystruct}
  870.              STRUCT anystruct
  871.                INT 0,10240,512
  872.                LONG $c00000,anylabel,4
  873.                CHAR 0,25,'anystring\n\0',34,227
  874.              ENDSTRUCT
  875.  
  876. -----------
  877. LOOP, ENDLOOP
  878. -----------
  879. syntax:      LOOP
  880.              ENDLOOP
  881. description: builds an infinite loop. Must end with ENDLOOP. be sure there
  882.              is an exit out of the loop.
  883. example:     LOOP
  884.                WRITE 'An everlasting loop\n'
  885.              ENDLOOP
  886.  
  887. -----------
  888. MLONG,MINT,MCHAR
  889. -----------
  890. syntax:      MLONG address,value
  891.                       or
  892.              value := MLONG(address)
  893. par:         address (exp) = any valid memory address, with MLONG and
  894.              MINT this needs to be at an equal address.
  895.              value (exp) = the value to be 'poked' into, or read from
  896.              that memorylocation.
  897. description: Commands similar to PEEK and POKE in basic, poke a longword,
  898.              word and byte respectively.
  899. example:     MCHAR $40000+a,b-1
  900.  
  901. -----------
  902. MOUSE, ENDMOUSE
  903. -----------
  904. syntax:      MOUSE
  905.              ENDMOUSE
  906. description: these make a loop that will be repeated as long as the
  907.              left mousebutton is not pushed.
  908. example:     MOUSE
  909.                VOID movesprites(x,y,3)
  910.                VOID playtune()
  911.              ENDMOUSE
  912.  
  913. -----------
  914. WRITE
  915. -----------
  916. syntax:      WRITE 'string'
  917. par:         'string' = any string of ascii signs, that may contain
  918.              codes with an '\' (see above for a discussion on strings
  919.              and codes).
  920. description: prints any string and/or integers etc. to standard output
  921.              (normally the cli/shell window); can be used to write to
  922.              files by saying:  stdout:=Open(...)  etc. 
  923. example:     PROC main()
  924.                WRITE 'Hello, World!\n'
  925.              ENDPROC
  926.  
  927. -----------
  928. PROC
  929. -----------
  930. syntax:      PROC name(par1, par2, ...) 
  931. par:         name,par = any normal string like 'dosomething', 'rastport'
  932.              these must be defined in this PROC as local variables.
  933. description: designates the beginning of a procedure. procedures should
  934.              not be nested, and the end of a procedure should always end
  935.              with an ENDPROC statement. Zero upto eight parameters can be
  936.              passed to localvars. Arguments for a PROC need to declared
  937.              as the first local variables in that module. for more info on
  938.              return values (as in example 2) see ENDPROC
  939.              Info on the main PROC can be found elsewhere
  940. example 1  : PROC screenflash()
  941.                VOID DisplayBeep(0)
  942.              ENDPROC
  943. example 2  : result=addition(x,y)
  944.              ...
  945.              PROC addition(value1, value2)
  946.                LOCAL value1:LONG, value2:LONG 
  947.              ENDPROC value1+value2
  948.  
  949. -----------
  950. REPEAT, UNTIL
  951. -----------
  952. syntax:      REPEAT
  953.              UNTIL equation
  954. description: The block within REPEAT/UNTIL is repeated as long as the
  955.              truth for the equation holds. Thus, this loop will always
  956.              be executed atleast once: the UNTIL will jump to the
  957.              beginning of the loop if the equation is TRUE.
  958. example:     REPEAT
  959.                Read(fh,buf,10)
  960.              UNTIL {buf}="quit"
  961.  
  962. -----------
  963. SIZEOF
  964. -----------
  965. syntax:      size := SIZEOF(label)
  966. description: SIZEOF returns the size of the STRUCT indicated by the label.
  967. example:     see STRUCT
  968.  
  969. -----------
  970. STRUCT, ENDSTRUCT
  971. -----------
  972. syntax:      STRUCT structname
  973.              ENDSTRUCT
  974. description: this statemenent adds a struct to your program. it can be
  975.              anywhere in the program, since it will be compiled to a
  976.              place separate from the code. see description of LONG etc.
  977.              for more info's. The statements CHIPSTRUCT and ENDCHIPSTRUCT
  978.              function exactly the same way, but will be allocated in
  979.              chipmem (handy for copperlists, see CMOVE etc.).
  980. example:     a := SIZEOF(newscreen)
  981.              STRUCT newscreen
  982.                INT 0,0,640,256
  983.                LONG 0,0, ... etc.
  984.                CHAR 'WindowTitle\0'
  985.              ENDSTRUCT
  986.  
  987. -----------
  988. WHILE, ENDWHILE
  989. -----------
  990. syntax:      WHILE equation
  991. par:         equation = (exp) comparison to be equated.
  992. description: the loop between WHILE and ENDWHILE is repeated as long as
  993.              the equation is TRUE. the program will continue after
  994.              ENDWHILE as soon as the equation is false. this loop must
  995.              end with ENDWHILE.
  996. example:     WHILE a/3+1 > 100
  997.                a := a-1
  998.              ENDWHILE
  999.  
  1000.  
  1001.  
  1002. ------------------------------------------------------------------------
  1003.                         6. FUNCTION OVERVIEW
  1004. ------------------------------------------------------------------------
  1005.  
  1006. The 30 all new functions can be divided into 5 intuition, 3 mouse, 8
  1007. Dos/miscelanious programming functions and 14 string functions,
  1008. which will be discussed at the end.
  1009.  
  1010. ------------------------------------------
  1011. OpenW() OpenS() CloseW() CloseS() Gadget()
  1012. ------------------------------------------
  1013.  
  1014. wptr:=OpenW(x,y,width,height,IDCMP,wflags,title,screen,sflags,gadgets)
  1015.  
  1016. creates a window where wflags are flags for window layout
  1017. (like BACKDROP, SIMPLEREFRESH e.d, usually $F) and sflags are
  1018. for specifying the type of screen to open on (1=wb,15=custom).
  1019. screen must only be valid if sflags=15, else NIL will do.
  1020. gadgets may point to a glist structure, which you can easily
  1021. create with the Gadget() function, else NIL.
  1022.  
  1023. VOID CloseW(wptr)
  1024.  
  1025. closes that screen again. only difference from CloseWindow()
  1026. is that it accepts NIL-pointers.
  1027.  
  1028. sptr:=OpenS(width,height,depth,sflags,title)
  1029.  
  1030. opens a custom screen for you. sflags is again mostly 15.
  1031.  
  1032. VOID CloseS(sptr)
  1033.  
  1034. as CloseW(), now for screens.
  1035.  
  1036. glistvar:=Gadget(buffer,glist,id,flags,x,y,width,string)
  1037.  
  1038. This function to create a list of gadgets, which can then be put in your
  1039. window by giving them as an argument to OpenW(), or afterwards with
  1040. intuition functions like AddGlist().
  1041. buffer is mostly an ARRAY of atleast 120 bytes to hold all the structures
  1042. associated with one gadget, id is any number that may help you remember as
  1043. to which gadget was pressed when an IntuiMessage arrives.
  1044. flags are: 0=normal gadget, 1=boolean gadget, 3=boolean gadget that is
  1045. selected. width is width in pixels, that should be large enough to hold
  1046. the string, which will be auto-centered. glist should NIL for the first
  1047. gadget, and glistvar for all others, so DEX may link all gadgets.
  1048. example for three gadgets:
  1049.  
  1050. DEF buf=360:ARRAY, mygadget:LONG, wptr:LONG
  1051. mygadgets:=Gadget(buf,NIL,... )                 /* the 1st gadget */
  1052. VOID Gadget(buf+120,mygadgets,... )
  1053. VOID Gadget(buf+240,mygadgets,... )             /* any amount linked 2 1st */
  1054. wptr:=OpenW( ...,mygadgets)
  1055.  
  1056. See QuickLaunch.Dex for an example of these functions.
  1057.  
  1058.  
  1059. -------------------------
  1060. Mouse() MouseX() MouseY()
  1061. -------------------------
  1062.  
  1063. code:=Mouse()
  1064.  
  1065. gives you the current state of all 2 or 3 mousebuttons; left=1,
  1066. right=2 and middle=4. if for example code=3 then left and right were
  1067. pressed together.
  1068.  
  1069. x:=MouseX()      and     y:=MouseY()
  1070.  
  1071. enables you to read the mouse coordintes. these are always in highest
  1072. resolution (640x512, or even more), so you need to scale them if
  1073. your app works in a lower resolution.
  1074.  
  1075.  
  1076. ------------------------------------------------------------------
  1077. And() Or() Not() Out() Inp() KickVersion() Filelenght() SetTopaz()
  1078. ------------------------------------------------------------------
  1079.  
  1080. a:=And(b,c)    and    a:=Or(b,c)    and    a:=Not(b)
  1081.  
  1082. These work with the usual operations, boolean as well as arithmetical.
  1083.  
  1084. VOID Out(filehandle,char)        and        char:=Inp(filehandle)
  1085.  
  1086. Either write or read one single byte to some file or stdout
  1087. if char=-1 then an EOF was reached, or an error occured.
  1088.  
  1089. bool:=KickVersion(vers)
  1090.  
  1091. Will give TRUE if the kickstart in the machine your program is running
  1092. on is equal or higher than vers, else FALSE
  1093.  
  1094. len:=FileLenght(namestring)
  1095.  
  1096. let's you determine the lenght of a file you *may* wish to load, and
  1097. also, if it exists (returns -1 upon error/file not found).
  1098.  
  1099. VOID SetTopaz(rast,size)
  1100.  
  1101. let's you set the font of the rastport to topaz, just to be sure that
  1102. some custom systemfont of the user won't trash your window layout.
  1103. size is ofcourse 8, 9 or (11)
  1104.  
  1105.  
  1106. ----------------
  1107. String Functions
  1108. ----------------
  1109.  
  1110. Starting at v1.15, DEX has a datatype STRING. This is a string, from
  1111. now on called 'Dstring', that maybe modified and changed in size,
  1112. as opposed to normal strings, usually called 'Cstrings'. Dstrings are
  1113. downward compatible with Cstrings, but not the other way around, so if
  1114. an argument request a normal string, it can be either of them.
  1115. If a dstring is requested, don't use cstrings.
  1116. example on the usage:
  1117.  
  1118. DEF s=80:STRING, n:LONG          /* s is a dstring with a maxlen of 80 */
  1119. VOID ReadStr(stdout,s)           /* read input from the console */
  1120. n:=Val(s)                        /* get a number out of it */
  1121.   ... etc.
  1122.  
  1123. Note that all 14 functions will handle cases where string tends to
  1124. get longer than the maximum lenght correctly;
  1125.  
  1126. DEF s=5:STRING
  1127. VOID StrAdd(s,'this string is longer than 5 characters',TRUE)
  1128.  
  1129. s will contain just 'this '.
  1130.  
  1131.  
  1132. bool:=StrCmp(string,string,len)
  1133. compares two strings. len must be the number of bytes to compare,
  1134. or TRUE if the full lenght is to be compared.
  1135.  
  1136. VOID StrCopy(Dstring,string,len)
  1137. copies the string into the dstring. if len=TRUE, all will be copied.
  1138.  
  1139. VOID StrAdd(Dstring,string,len)
  1140. same as StrCopy(), only now the string is concatenated to the end.
  1141.  
  1142. len:=StrLen(string)
  1143. calculates the lenght of a string
  1144.  
  1145. len:=DstrLen(dstring)
  1146. returns the lenght of a dstring
  1147.  
  1148. max:=StrMax(dstring)
  1149. returns the maximum lenght of a dstring
  1150.  
  1151. VOID RightStr(dstring,string,n)
  1152. fills dstring with the n rightmost characters of a string
  1153.  
  1154. VOID MidStr(dstring,string,pos,len)
  1155. copies any number of characters (including all if len=TRUE) from
  1156. position pos in string to dstring
  1157. NOTEZ BIEN: in all string related functions where a position in a
  1158. string is used, the first character in a string has position 0,
  1159. not 1, as used in languages like BASIC.
  1160.  
  1161. value:=Val(string)
  1162. finds an integer encoded in ascii out of a string. leading spaces will
  1163. be skipped, and also hexadecimal numbers (1234567890ABCDEF) may
  1164. be read this way if they are preceded by a '$' sign.
  1165. Val()  returns -1 if the string did not contain an integer, or
  1166. the value was too sizy to fit in a LONG.
  1167.  
  1168. foundpos:=InStr(string1,string2,startpos)
  1169. searches string1 for the occurence of string2, possibly starting from
  1170. another position than 0. returned is the position at which the substring
  1171. was found, else -1.
  1172.  
  1173. newadr:=TrimStr(string)
  1174. returns the *address* of the first character in a string, i.e., after
  1175. leading spaces, tabs etc.
  1176.  
  1177. VOID UpperStr(dstring)     and      VOID LowerStr(dstring)
  1178. changes the case of a string. may also be used on cstrings if
  1179. these are part of your program's data, since the string is modified,
  1180. but not changed in size.
  1181.  
  1182. ok:=ReadStr(filehandle,dstring)
  1183. will read a string (ending in ascii 10) from any file or stdout.
  1184. ok contains -1 if an error occurred, or an EOF was reached.
  1185.  
  1186.  
  1187.  
  1188. ------------------------------------------------------------------------
  1189.                 7. ADVANCED PROGRAMMING AND LANGUAGE INFO'S
  1190. ------------------------------------------------------------------------
  1191.  
  1192. This chapter is about:
  1193.  
  1194. - DEX <-> Assembly conventions.
  1195. - Code generated by DEX / Optimizing.
  1196. - Debugging.
  1197. - EBNF overview of DEX syntax.
  1198. - DEX as a language concept / The future of DEX / All new EEX compiler.
  1199.  
  1200.  
  1201. To use the inline assembly feature without trouble, it's best to
  1202. know a few things about TurboDEX code-generation:
  1203.  
  1204. Register use: normally you may trash ALL (except A7, ofcourse!)
  1205. registers, since none are used to point at vital data during the
  1206. course of the program. However, REG variables are stored in D2-D7,
  1207. (starting with D7) so if you use these in your DEX code, you may not
  1208. trash these. Using REG-variables can also be a fine way to allocate
  1209. a register for permanent use in a PROC, for example:
  1210.  
  1211. PROC bla()
  1212.   LOCAL a:REGINT, b:REGLONG
  1213.   ...
  1214.   ASM
  1215.     ...  (use D6(=b), D7(=a) here)
  1216.   ENDASM
  1217.   ...    (use a,b here)
  1218. ENDPROC
  1219.  
  1220. In this module you could store something permanent in D6/D7, without
  1221. the danger of getting them trashed: DEX will preserve these registers
  1222. if they need to be used for a (system-)functioncall.
  1223. This is the sort of PROC-setup you'd be using to obtain very optimized
  1224. code.
  1225.  
  1226. D0-D1/A0-A1 may ofcourse be trashed by assembly as well as DEX code.
  1227. Functions like WRITE are likely to trash more address-registers than
  1228. just these.
  1229.  
  1230. Sharing local and global variables:
  1231. Each variable has a label that can be used to access DEX-variables
  1232. from within the inline assembler, they are build as folows:
  1233.  
  1234. ModuleName + 'var' + VariableName
  1235.  
  1236.           PROC bla()
  1237. Example:    DEF screen:LONG      gives EA:   mainvarscreen
  1238.             LOCAL a:INT                      blavara
  1239.           ENDPROC
  1240.  
  1241. note that global variables always have ModuleName = 'main'
  1242.  
  1243. if you want to have an overview of the each effective address
  1244. then compile your program with option -l, also have a look at the
  1245. source (the .s file) TurboDEX generates to get the idea.
  1246.  
  1247. Accessing of labels and arrays is just as easy:
  1248.  
  1249. PROC main()                 will yield:     proglabmain
  1250. DEF string=80:ARRAY                         arraylabstring
  1251. start:                                      proglabstart
  1252. STRUCT newscreen                            proglabnewscreen
  1253.  
  1254. If your program uses functions from a certain library, the base of
  1255. that library can be accessed by LibraryName + 'base' (f.e. dosbase).
  1256.  
  1257. Debugging hints:
  1258. Apart from debuggingmethods that may be used on any language/compiler,
  1259. following are specifically handy with DEX:
  1260. - expressions: as these are different from other other languages,
  1261.   it's very likely mistakes are made: check out the order of
  1262.   operators/comparison's, problems that may occur when using/comparing
  1263.   variables of different sizes (LONG/CHAR) etc.
  1264. - compile with -l to see if you possibly made errors in declaration
  1265.   of variables etc.
  1266. - check variables that contain pointers, as DEX does no type-checking
  1267. - throwing the assembly source through a source-level debugger will
  1268.   mostly indicate the problem :-) .
  1269.  
  1270. BNF overview of the language:
  1271. The compiler-builders under the readers may find it clarifying
  1272. to see some structural elements formalized (not complete): 
  1273.  
  1274. <program> ::= { <procedure> }
  1275. <procedure> ::= PROC <label> ( <definitionlist> )
  1276.         { <defstatement> | <localstatement> }
  1277.         { <statementblock }
  1278.         ENDPROC <exp>
  1279. <label> ::= <ident>
  1280. <variable> ::= <ident>
  1281. <ident> ::= <letter> { <character> }
  1282. <character> ::= <letter> | <digit>
  1283. <definitionlist> ::= <definition> { , <definition> }
  1284. <definition> ::= <variable> : <type> | 
  1285.         <variable> = <integer> : <type> |
  1286.         <variable> [ <absolute> ] : <type>
  1287. <type> ::= CHAR | INT | LONG | REGLONG | REGCHAR | REGINT |
  1288.         ARRAY | ARRAYCHIP
  1289. <integer> ::= <digit> { <digit> } |
  1290.         $ <hexcharacter> { <hexcharacter> }
  1291.         % 0 | 1 { 0 | 1 }
  1292. <absolute> ::= <integer> | <label> . <integer>
  1293. <defstatement> ::= DEF <definitionlist>
  1294. <localstatement> ::= LOCAL <definitionlist>
  1295. <statementblock> ::= { <statement> | <assignment> }
  1296. <exp> ::= <empty> | <expitem> { <operator> <expitem> }
  1297. <empty> ::=
  1298. <expitem> ::= <integer> | <variable> | '{' <label> '}' | " <ascii's> " |
  1299.         ' <ascii and format characters> '
  1300. <operator> ::= + | - | * | / | & | ^ | = | > | < | ?
  1301. <assignment> ::= <variable> := { <exp> | <procedurecall> |
  1302.         <function> | <systemcall> }
  1303. <procedurecall> ::= <label> <argumentlist>
  1304. <function ::= <keyword> <argumentlist>
  1305. <systemcall> ::= <amigasystemcall> <argumentlist>
  1306. <argumentlist> ::= () | ( <exp> { , <exp> } )
  1307. <statement> ::= { <structuralstatement> | <otherstatement> }
  1308. <structuralstatement> ::= <conditionalstatement> | <loopstatement>
  1309. <loopstatement> ::= <repeatstatement> | <forstatement> | ...
  1310. <repeatstatement> ::= REPEAT <statementblock> UNTIL <exp>
  1311. <forstatement> ::= FOR <variable> , <exp> , <integer>
  1312.         <statementblock> ENDFOR
  1313. <conditionalstatement> ::= <ifstatement> | ...
  1314. <ifstatement> ::= IF <exp> <statementblock> ENDIF |
  1315.         IF <exp> <statementblock> <elseblock> ENDIF
  1316. <elseblock> ::= { ELSEIF <exp> <statementblock> } |
  1317.         { ELSEIF <exp> <statementblock> } ELSE <statementblock>
  1318.  
  1319. Some definitions are missing, some things are simplified, and
  1320. of all instructions only a few are taken as an example. Just
  1321. to give the reader a view on the matter.
  1322.  
  1323.  
  1324.  
  1325. DEX as a language concept.
  1326. As you might have noticed, DEX is not a complicated language when
  1327. it comes to structural and typological elements. It belongs to
  1328. a family of two languages sofar, and is derived from the language E,
  1329. which inturn has mostly been influenced by Modula2 and some C.
  1330. In DEX only the fundamentals of E are left, nearly all advanced features
  1331. of the language are not contained in DEX, and DEX has few enhancements,
  1332. some as replacement of the proffessional features in E, others just
  1333. Amiga-specific add-ons.
  1334.                                E
  1335.                               / 
  1336.                              /   
  1337.                             /
  1338.                           DEX
  1339.  
  1340. Very worthwhile noting here is that a Amiga-specific E compiler
  1341. is being developped right now, and most important features of
  1342. this all new compiler are:
  1343. - about 40x (no joke!) the speed of the Dex compiler. (the compiler
  1344.   is programmed in assembly)
  1345. - doesn't generate assembly source, but executables straight away.
  1346.   No need of seperate assemblers/linkers.
  1347. - Nearly full E language standard i.e. much more powerfull than Dex.
  1348. - Reliable compiler operation/code generation, adequate for quick
  1349.   and stable development of big app's
  1350. - includes own (inline) assembler that does up to 40000 lines/minute.
  1351. - able to generate 1.2 compatible code, as well as 2.x specific
  1352.   app's: all 2.0 library modules included.
  1353.  
  1354. Import characteristics of E (and to some extend, also DEX and EEX)
  1355. as opposed to typical influences such as Modula2 (and some C) are:
  1356.  
  1357. 1. The Principle of True Inline Assembly:
  1358.    As no higher programming language can be an 'ideal' programming
  1359.    language, because only Assembly is, E has the feature of true
  1360.    inline assembly: assembly instructions are part of the language,
  1361.    and are equal to E instructions when it comes to using identifiers
  1362.    etc. Note that DEX has this feature only partly
  1363. 2. The Principle of System-Integration:
  1364.    the E language has OS-specific features in the core of the language.
  1365.    Because of 1 and 2 principle 3 automatically holds:
  1366. 3. The Principle of Non-Portability:
  1367.    Languages like DEX and E are designed to be nonportable: Programs
  1368.    should use machine-specific features (in this case AmigaOs 1.2 and
  1369.    up) for highest quality app's.
  1370. 4. The Principle of the Typeless Variables:
  1371.    E is Typeless. Types, as do exist in DEX, are gathered to one,
  1372.    as for example in EEX, where all types are LONG.
  1373.  
  1374. So, Those portability-lovers among you programmers might just as
  1375. well copy this distribution to NIL:
  1376.  
  1377.  
  1378. ------------------------------------------------------------------------
  1379.                           8. ADDITIONAL INFO'S
  1380. ------------------------------------------------------------------------
  1381.  
  1382. TurboDEX Compiler v1.2 released as Public Domain in september 1992,
  1383. update from v1.1 on Fish #625
  1384.  
  1385. Together with this distribution you will find A68k, Blink and their docs,
  1386. see those for distribution contraints. Thanx go to Charlie Gibbs (A68k)
  1387. and The Software Distillery (Blink).
  1388.  
  1389. NOTE to future DEX coders: people that use DEX more than occasionally
  1390. and get stuck may count on full support by me, the compiler author. Send 
  1391. your unsolvable problems or requests for hints/tips/tricks/enhancements
  1392. to me (i prefer electronic above paper mail).
  1393.  
  1394. Needless to say, but: TurboDEX may be copied, crunched and used freely as
  1395. long as the full distribution is with it, and no modifications are made
  1396. to either the executable, the doc or the supportfiles.. Permission granted
  1397. for spreading on (pd) disk series other than that of Fred Fish if costs
  1398. are limited to a copy fee, otherwise you need my written permission.
  1399. I will personally RemHead() and AbortIO() those 'Pd-Distributors' that sell
  1400. this program for more than that.
  1401.  
  1402. Donations welcome, but certainly not obligatory.
  1403. Support quality PD and  Shareware! (i don't necessarily mean this program by that).
  1404.  
  1405. the address:
  1406.  
  1407.          Wouter van Oortmerssen ($#%!)
  1408.          Levendaal 87
  1409.          2311 JG  Leiden
  1410.          HOLLAND
  1411.  
  1412. Or even better Email:
  1413.  
  1414.          Wouter@alf.let.uva.nl
  1415.  
  1416.